C/C++ Users Group Library 1996 July/C-C++ Users Group Library July 1996.iso/vol_400/438_01/stelnet.doc

Text File | 1994-12-20 | 10.5 KB | 245 lines

stelnet - A telnet client for the serial port
Version 1.00 (December 20th, 1994)

Documentation

        Copyright information

Copyright 1994 Riku Saikkonen ([e-mail])

This program is free software; you can redistribute and/or modify it
under the terms of the GNU General Public License version 2 as published
by the Free Software Foundation.

This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
Public License for more details.

You should have received a copy of the GNU General Public License along
with this program (as the file COPYING); if not, write to the Free
Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

The author, Riku Saikkonen, can be contacted via the following means:
E-mail: [e-mail] (preferred) or
        [e-mail]
Paper mail: Riku Saikkonen
            Alakartanontie 4 B 63
            SF-02360  ESPOO
            Finland

        Description

stelnet is a telnet client for MS-DOS, using the serial port (via a FOSSIL
driver) as the I/O device. It was meant for BBS (Bulletin Board System)
use, but works equally well without any BBS software.

stelnet supports binary mode telnet (8-bit), and a '8-bit clean mode', in
which all 256 characters are cleanly transferred in both directions.

stelnet does not do any terminal emulation of its own; it should never
change the data transferred (except, of course, in IACs and client
commands).

stelnet is distributed under the GNU General Public License, version 2, and
thus includes source code.

        Features

stelnet is a 'conditionally compliant' (in the definition of RFC 1123)
telnet client.

The serial port code uses normal FOSSIL interrupts. The 'Read block' and
'Write block' commands are used for the transfer. The FOSSIL driver is
initialised at the start and deinitialised at the end. stelnet does not
set the bps rate of the port. The program should work with any COM port
supported by the FOSSIL driver.

The telnet code uses the Waterloo TCP library (WATTCP), which uses a packet
driver. Any network adapter with a packet driver should work. SLIP should
work, at least with the EtherSLIP packet driver.

Telnet options supported are the Binary option, the Echo option, the
Suppress Go Ahead option (stelnet never sends GAs), and the Terminal-Type
option. The terminal type is currently fixed at 'DEC-VT100' in the source;
I will probably make it user-selectable in a future version. stelnet also
sends a couple of VT-100 escape codes to the serial port; search the source
for 'VT-100' for the details. Telnet option negotiation is supported at any
time during the connection. stelnet can send the NVT special codes with
client options.

The client options are activated with a user-selectable escape character,
ASCII code 255 by default. The 8-bit clean mode disables this escape
character (and instead passes it through it to the telnet port).

Both the telnet and serial ports are double-buffered.

        Compiling it yourself

The included binary (stelnet.exe) should do well for most applications, but
if you want to compile it yourself for some reason, here's how.

First edit the included makefile, especially the paths to your compiler and
the WATTCP library. If you haven't compiled the WATTCP library yet, do it
before compiling stelnet. The makefile looks for the WATTCP library in
..\lib; I suggest you put stelnet in its own directory under the WATTCP top
directory (e.g. if WATTCP is at c:\wattcp, put stelnet to
c:\wattcp\stelnet). Or change the directory in the definition of CLIB.

Then, just execute 'make' and you should have a binary.

The default compile-time options (OPTIONS=-D... in the makefile) should
work pretty well for most uses, but if you want to modify them, here is a
description:

SIBLEN and TIBLEN are the serial and telnet input buffer sizes, in bytes.
This buffer is always emptied at once (to the output buffers), so the sizes
needn't be very large. Think of the options as specifying the 'chunk size'
for incoming data.

SOBLEN and TOBLEN are the sizes of the serial and telnet output buffers,
again in bytes. These are the main buffers of the programs so they should
be a bit larger.

SOBLIMIT is kind of a kludge to generate a bit of handshaking into the
telnet protocol. The option simply ceases reading from the telnet
connection if the serial output buffer is almost full (it has SOBLIMIT
bytes or less of free space). It is kind of weird, but it seems to work...
(If anyone knows of a better method for telnet handshaking that preserves
all characters in the input stream (XON/XOFF doesn't), tell me!) Defining
the value to 0 removes the limit, but this usually causes buffer overruns
(and thus lost characters). A good value for the limit is TIBLEN.

stelnet runs in a loop, reading and writing as much as it can at every cycle.
Every LOOPCHECK cycles, it checks that the connections are working (carrier
detection, idle timeout, time left, ...). This isn't done on every cycle,
because it would slow the connection down a bit. Every LOOPCHECK*LOOPCHECK
cycles, stelnet displays information about the connection on the local
screen (if the l option is not specified on the command line).

There are a few commented-out lines and '!!!' marks in the source code;
these usually signify a slightly kludgy piece of code or a place to add
some feature in the to-do list to.

The binary included in the package was compiled using Borland C++ 3.0 and a
version of the WATTCP library from November 14th, 1994. I found a couple of
bugs in the compiler (or at least I couldn't explain a few irregularities
in any other way); the workarounds are detailed in the source (search for
'BC++ 3.0 bug'). The binary was compiled with the default compile-time
options.

        Modifying stelnet

Feel free to modify the source code if you wish, but keep the copyright
notices. I would appreciate it if you sent me any added features or bug
reports... I can read the complete new source, a Unix-style 'diff' or 'diff
-u', a human-written difference text, or even an MS-DOS 'fc' output dump.

        Executing the program

The program syntax is:
    stelnet <comport> <host> <port> [options]
where
    comport = COM port number (1-8)
    host = the host name or IP address to connect to
    port = the TCP/IP port to connect to (23 is the telnet port)
    options = a list of options (as separate arguments)

The options:
    t<n> = set a n-minute time limit
    i = set a 5-minute idle timeout
    l = show the connection on the local screen and read the keyboard (this
        currently makes the connection quite slow)
    c = disable Carrier Detect detection on the serial port
    x = don't send telnet/serial initialisation codes (for connecting to
        a finger, NNTP or similar port that does not run telnetd; this
        option disables both the telnet protocol initialisation IACs and
        the VT-100 reset code sent to the serial port)
    8 = enter 8-bit clean mode at the start of the program
    e<code> = set the serial port escape character to ASCII code <code>
      (default 255)
    d<t><filename> = read a door information file:
      <t> = type (see below)
      <filename> = full file name (with a possible path)
      The only type currently defined is p = PCBOARD.SYS.

Some examples:

    stelnet 1 10.0.0.1 23 t60 i l e33
connects to 10.0.0.1 port 23, using serial port 1, an idle timeout and
showing the connection on the local screen, using '!' (ASCII code 33) as
the escape character.

    stelnet 2 hosta.xxx.fi 23 dpc:\pcb\node1\pcboard.sys
connects to hosta.xxx.fi port 23, using serial port 2 and reading
c:\pcb\node1\pcboard.sys as a PCBOARD.SYS-type door file.

    stelnet 1 10.0.0.2 79 x
connects to the finger port (port 79) of 10.0.0.2, and does not send the
initialisation codes.

The errorlevels stelnet returns are:
  0 = a normal exit
  1 = the user ran out of time (or hit the idle timeout)
  2 = the telnet connection was refused
  3 = a serial port error (initialisation failure, carrier detect lost,
      ...)
  4 = a network error (e.g. name server failure)
  9 = an error in reading the door information file
  10 = an error in the command line

        Running the program

Anything sent to the serial port is sent to the telnet port, and vice
versa. The only exceptions are the IAC for telnet (which processes telnet
options; an IAC IAC is recognised as an ASCII 255 character and sent to the
serial port) and the client escape character, ASCII 255 by default, for the
serial port.

The escape character is used to send special telnet characters and issue
commands to stelnet from the serial port. The user should send the escape
character and the command character following it to the serial port.

The client commands are:

c Forcefully close the connection and exit stelnet
8 (in binary mode) Enter 8-bit clean mode. The mode is exited by sending
  the sequence <command key> + <^X> (ASCII 24) + <^X> + "stelnet" (without
  the quotes) to the serial port
i Send telnet Interrupt Process code (IAC IP)
r Send telnet NVT BRK code (IAC BRK)
a Send telnet Abort Output code (IAC AO)
t Send telnet Are You There code (IAC AYT)
e Change the escape character to the next key typed after this command
s Display some status information about stelnet; this does not use the
  telnet STATUS option, which stelnet currently does not support
? Display a help text of these commands
<escape char> (i.e. press the escape character twice) Send the escape
              character to the telnet port

        Bugs, to do

See the start of the source code for a list of known bugs and a to-do list.
I accept bugfixes and added features gladly :).

See stelnet.bug for a description of one possible bug.

If you find a bug, e-mail me about it and I'll try to fix it...

        FTP sites

stelnet should later be put to the SimTel MS-DOS archive (I hope they'll
accept it :)), probably to the msdos/bbs directory. In the meantime, e-mail
me (my contact information is at the start) for a copy of the latest
version... The filename is stlnt100.zip.

The official FTP site for WATTCP is dorm.rutgers.edu: /pub/msdos/wattcp.
Get wattcp.zip there for the newest source for the library.

Free packet drivers are in the SimTel archive, e.g. oak.oakland.edu:
/pub/SimTel/msdos/pktdrvr/drivers.zip.

        Have fun!

End of stelnet.doc.